Bulk Messaging System

Documentation

Back to Home
GitHub
Project Overview
Getting Started

API Reference

Configuration Parameters
Environment Variables Gmail Oauth 2 Configuration SMTP Configuration Whats App Client Configuration
Electron IPC API
File Operations IPC Gmail & SMTP IPC Handlers Whats App Event System Whats App IPC Handlers
Python Backend API
File Upload Endpoint Health Check Endpoint Manual Number Parsing Endpoint Phone Number Validation Endpoint

Contact Management System

File Import And Processing Manual Contact Entry Interface Phone Number Validation And Normalization Pyodide Runtime Integration

Desktop Application Architecture

Main Process Architecture
Cleanup And Lifecycle Management File System Operations IPC Handlers Whats App Client Integration Window Management
Renderer Process Architecture
Component Hierarchy And Structure State Management And Data Flow UI Service Integration And IPC Communication
Build System And Distribution Security Model And Isolation

Gmail API Integration

Authentication And Delivery Troubleshooting Email Composition And Sending Oauth 2 Authentication Flow Token Storage And Management

Python Backend Services

Contact Extraction Utilities
CSV File Extraction Excel File Extraction TXT File Extraction
Flask API Endpoints Local Development Server Phone Number Validation

SMTP Email Integration

SMTP Authentication SMTP Email Sending Implementation SMTP Server Configuration SMTP Troubleshooting And Error Handling

Security Implementation

Authentication Security
Credential Storage And Encryption Gmail Oauth 2 Security SMTP Authentication Security Whats App Local Auth Security
Credential Storage And Encryption Electron Security Model Input Validation And Sanitization

Whats App Integration

Authentication And Session Management Bulk Sending Engine Contact Import And Management Message Composition And Templates Status Monitoring And Progress Tracking
Build And Deployment
Development Guidelines
Frontend User Interface
Troubleshooting Guide
Home Projects Bulk Messaging System API Reference Configuration Parameters Gmail Oauth 2 Configuration

Gmail Oauth 2 Configuration

Referenced Files
gmail-handler.jsmain.jspreload.jsGmailForm.jsxpackage.jsonREADME.mdelectron-builder.json
#

Table of Contents#

  1. Introduction

  2. Project Structure

  3. Core Components

  4. Architecture Overview

  5. Detailed Component Analysis

  6. Dependency Analysis

  7. Performance Considerations

  8. Troubleshooting Guide

  9. Conclusion

  10. Appendices

#

Introduction#

This document provides comprehensive configuration guidance for Gmail OAuth2 authentication in the application. It covers environment variables, OAuth2 flow, scopes, redirect URIs, token exchange, authentication window configuration, and step-by-step setup instructions for Google Cloud Console. It also includes troubleshooting guidance for common OAuth2 errors and best practices for credential storage.

#

Project Structure#

The Gmail OAuth2 integration spans the Electron main process, preload bridge, and React UI components. The main process handles OAuth2 flow and token persistence, while the renderer communicates via IPC.

graph TB UI["GmailForm.jsx
UI component"] --> Preload["preload.js
IPC bridge"] Preload --> Main["main.js
Electron main process"] Main --> Handler["gmail-handler.js
OAuth2 handler"] Handler --> GoogleAPIs["googleapis
Gmail API client"] Handler --> Store["electron-store
Token persistence"]

Diagram sources

Section sources

#

Core Components#

  • Environment variables:

    • GOOGLE_CLIENT_ID

    • GOOGLE_CLIENT_SECRET

  • OAuth2 configuration:

    • Scopes: Gmail send only

    • Redirect URI: localhost callback

    • Access type: offline (refresh token)

  • Token storage:

    • electron-store persists tokens locally

  • Authentication window:

    • Size: 800x800 pixels

    • Security: context isolation, no node integration

    • Timeout: 5 minutes

Section sources

#

Architecture Overview#

The OAuth2 flow is handled in the Electron main process. The renderer triggers authentication via IPC, the main process opens an embedded BrowserWindow, generates the authorization URL, captures the redirect, exchanges the authorization code for tokens, and stores them securely.

sequenceDiagram participant UI as "GmailForm.jsx" participant Preload as "preload.js" participant Main as "main.js" participant Handler as "gmail-handler.js" participant Google as "Google OAuth2" participant Store as "electron-store" UI->>Preload : "invoke('gmail-auth')" Preload->>Main : "ipc invoke('gmail-auth')" Main->>Handler : "handleGmailAuth()" Handler->>Handler : "check env vars" Handler->>Handler : "create OAuth2 client" Handler->>Google : "generateAuthUrl(access_type='offline', scope=['gmail.send'])" Handler->>Handler : "open BrowserWindow" Google-->>Handler : "redirect to REDIRECT_URI with code" Handler->>Google : "getToken(code)" Google-->>Handler : "token" Handler->>Store : "set('gmail_token', token)" Handler-->>Main : "{success : true}" Main-->>Preload : "{success : true}" Preload-->>UI : "{success : true}"

Diagram sources

#

Detailed Component Analysis#

Environment Variables and Security#

  • Required variables:

    • GOOGLE_CLIENT_ID

    • GOOGLE_CLIENT_SECRET

  • Storage recommendations:

    • Use a .env file in the electron directory

    • Do not commit secrets to version control

    • Restrict file permissions to owner-only

    • Consider platform keychain integration for production builds

Security implications:

  • Exposing client credentials allows unauthorized API access

  • Tokens grant full Gmail send privileges

  • Store tokens securely and rotate credentials periodically

Section sources

OAuth2 Flow and Authorization URL Generation#

  • Scope configuration:

    • Single scope: Gmail send

  • Access type:

    • offline to receive refresh tokens

  • Consent prompt:

    • prompt set to force consent screen for refresh token

  • Redirect URI:

flowchart TD Start(["Start Authentication"]) --> CheckEnv["Check GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET"] CheckEnv --> EnvOK{"Environment OK?"} EnvOK --> |No| Error["Return error: missing credentials"] EnvOK --> |Yes| CreateClient["Create OAuth2 client with REDIRECT_URI"] CreateClient --> GenAuthUrl["Generate authorization URL
access_type='offline'
scope=['gmail.send']
prompt='consent'"] GenAuthUrl --> OpenWindow["Open BrowserWindow"] OpenWindow --> Redirect["User authorizes and redirects"] Redirect --> HasCode{"Has authorization code?"} HasCode --> |No| NoCodeErr["Return error: no authorization code"] HasCode --> |Yes| Exchange["Exchange code for tokens"] Exchange --> TokenOK{"Token exchange OK?"} TokenOK --> |No| TokenErr["Return error: token exchange failed"] TokenOK --> |Yes| Store["Persist token with electron-store"] Store --> Success(["Authentication success"])

Diagram sources

Section sources

Redirect URI Configuration#

  • The application expects a redirect to http://localhost:3000/oauth/callback

  • Ensure this redirect URI is configured in the Google OAuth2 client configuration

  • The embedded BrowserWindow listens for this exact URL to capture the authorization code

Section sources

Token Exchange Process#

  • After redirect, the handler extracts the authorization code from the URL

  • It exchanges the code for tokens using the OAuth2 client

  • On success, sets credentials on the OAuth2 client and persists the token

  • On failure, returns an error response

sequenceDiagram participant Handler as "gmail-handler.js" participant Google as "Google OAuth2" participant Store as "electron-store" Handler->>Google : "getToken(code)" Google-->>Handler : "token" Handler->>Handler : "oauth2Client.setCredentials(token)" Handler->>Store : "set('gmail_token', token)" Handler-->>Caller : "{success : true}"

Diagram sources

Section sources

Scope Configuration for Gmail API Access#

  • Current scope: Gmail send only

  • Implication: Application can only send emails; no read or manage permissions

  • If broader access is needed, adjust the scope accordingly

Section sources

Offline Access Type and Refresh Tokens#

  • access_type set to offline ensures a refresh token is issued

  • The consent prompt forces explicit user consent for offline access

  • The application stores the token for future use without re-prompting

Section sources

Authentication Window Configuration#

  • Size: 800x800 pixels

  • Security:

    • contextIsolation enabled

    • nodeIntegration disabled

    • show initially hidden, shown on ready-to-show

  • Timeout: 5 minutes; closes window if not redirected within this period

Section sources

Step-by-Step Setup Instructions#

Google Cloud Console Setup#

  1. Navigate to Google Cloud Console.

  2. Create or select a project.

  3. Enable the Gmail API for the project.

  4. Go to Credentials and create OAuth 2.0 Client IDs.

  5. Configure the OAuth consent screen.

  6. Create desktop application credentials.

  7. Download the credentials JSON file.

OAuth2 Client Creation#

Credential Configuration#

  • Place the downloaded credentials in the electron directory

  • Create a .env file with:

    • GOOGLE_CLIENT_ID=your_client_id_here

    • GOOGLE_CLIENT_SECRET=your_client_secret_here

Running the Application#

  • Install dependencies in the electron directory

  • Start the development server

  • Use the Gmail tab to authenticate and send emails

Section sources

#

Dependency Analysis#

External dependencies involved in Gmail OAuth2:

  • googleapis: Provides OAuth2 client and Gmail API access

  • electron-store: Persists tokens locally

  • dotenv: Loads environment variables from .env

graph TB Handler["gmail-handler.js"] --> GoogleAPIs["googleapis"] Handler --> Store["electron-store"] Handler --> Dotenv["dotenv"] Package["electron/package.json"] --> GoogleAPIs Package --> Store Package --> Dotenv

Diagram sources

Section sources

#

Performance Considerations#

  • Token reuse: The application reuses stored tokens to avoid repeated authentication prompts

  • Rate limiting: The UI allows configuring delay between emails to avoid throttling

  • Window lifecycle: Authentication window is closed after successful token exchange or timeout

[No sources needed since this section provides general guidance]

#

Troubleshooting Guide#

Common OAuth2 errors and resolutions:

  • Missing environment variables:

    • Ensure GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are present in .env

  • Redirect URI mismatch:

  • Token exchange failures:

    • Verify client credentials and network connectivity

    • Check for invalid_grant or expired token scenarios

  • Authentication timeout:

    • Increase timeout if needed or ensure the redirect occurs promptly

  • Window closed prematurely:

    • Ensure the BrowserWindow remains open until redirect completes

Credential storage best practices:

  • Store tokens securely using electron-store

  • Avoid exposing tokens in logs or UI

  • Rotate client credentials periodically

  • Use separate OAuth2 clients for development and production

Section sources

#

Conclusion#

The application implements a secure, offline-capable Gmail OAuth2 flow with a dedicated authentication window and robust token persistence. By following the setup instructions and best practices outlined here, you can configure Gmail API access safely and reliably.

[No sources needed since this section summarizes without analyzing specific files]

#

Appendices#

Appendix A: Environment Variable Reference#

  • GOOGLE_CLIENT_ID: OAuth2 client identifier

  • GOOGLE_CLIENT_SECRET: OAuth2 client secret

Storage recommendations:

  • Use .env file in electron directory

  • Restrict file permissions

  • Do not commit to version control

Section sources

Appendix B: Build and Distribution Notes#

  • The application uses electron-builder for cross-platform builds

  • Ensure environment variables are available at runtime for distribution builds

Section sources

Previous Environment Variables
Next SMTP Configuration